# 版本: 0.5.0.20240803
# 作者: 陈振玺
# 功能: 通用工具函数集合

"""Utility functions for common tasks."""

import os
import json
from typing import Any, Dict, List, Optional, Union
from pathlib import Path
from loguru import logger


# 配置loguru日志格式
logger.remove()  # 移除默认的日志处理器
logger.add(
    "logs/toolbelt_{time:YYYY-MM-DD}.log",
    rotation="1 day",
    retention="7 days",
    level="DEBUG",
    format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {name}:{function}:{line} - {message}",
    enqueue=True,  # 线程安全
    backtrace=True,  # 更详细的错误追踪
    diagnose=True    # 诊断信息
)

# 同时输出到控制台
logger.add(
    lambda msg: print(msg, end=""),
    format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {name}:{function}:{line} - {message}",
    level="INFO"
)


class ToolbeltLogger:
    """Toolbelt日志类，基于loguru实现"""
    
    @staticmethod
    def debug(message: str) -> None:
        """记录调试信息"""
        logger.debug(message)
    
    @staticmethod
    def info(message: str) -> None:
        """记录一般信息"""
        logger.info(message)
    
    @staticmethod
    def warning(message: str) -> None:
        """记录警告信息"""
        logger.warning(message)
    
    @staticmethod
    def error(message: str) -> None:
        """记录错误信息"""
        logger.error(message)
    
    @staticmethod
    def critical(message: str) -> None:
        """记录严重错误信息"""
        logger.critical(message)


def read_json(file_path: Union[str, Path]) -> Dict[str, Any]:
    """读取JSON文件并返回字典。
    
    Args:
        file_path: JSON文件路径
        
    Returns:
        解析后的字典对象
        
    Raises:
        FileNotFoundError: 文件不存在
        json.JSONDecodeError: JSON格式错误
    """
    with open(file_path, 'r', encoding='utf-8') as f:
        return json.load(f)


def write_json(data: Dict[str, Any], file_path: Union[str, Path], indent: int = 2) -> None:
    """将字典写入JSON文件。
    
    Args:
        data: 要写入的数据
        file_path: 输出文件路径
        indent: JSON缩进空格数
    """
    with open(file_path, 'w', encoding='utf-8') as f:
        json.dump(data, f, ensure_ascii=False, indent=indent)


def ensure_dir(dir_path: Union[str, Path]) -> Path:
    """确保目录存在，如果不存在则创建。
    
    Args:
        dir_path: 目录路径
        
    Returns:
        Path对象
    """
    path = Path(dir_path)
    path.mkdir(parents=True, exist_ok=True)
    return path


def flatten_list(nested_list: List[Any]) -> List[Any]:
    """展平嵌套列表。
    
    Args:
        nested_list: 嵌套列表
        
    Returns:
        展平后的列表
    """
    result = []
    for item in nested_list:
        if isinstance(item, list):
            result.extend(flatten_list(item))
        else:
            result.append(item)
    return result


def chunk_list(lst: List[Any], chunk_size: int) -> List[List[Any]]:
    """将列表分割成指定大小的块。
    
    Args:
        lst: 要分割的列表
        chunk_size: 每块的大小
        
    Returns:
        分割后的列表块
    """
    return [lst[i:i + chunk_size] for i in range(0, len(lst), chunk_size)]


def safe_get(dictionary: Dict[str, Any], key: str, default: Any = None) -> Any:
    """安全地从字典中获取值，支持嵌套键。
    
    Args:
        dictionary: 字典对象
        key: 键名，支持点分隔的嵌套键如 'a.b.c'
        default: 默认值
        
    Returns:
        获取到的值或默认值
    """
    keys = key.split('.')
    current = dictionary
    
    for k in keys:
        if isinstance(current, dict) and k in current:
            current = current[k]
        else:
            return default
    
    return current


def example_function() -> str:
    """示例函数。
    
    Returns:
        示例字符串
    """
    return "Hello from Toolbelt!"